IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/librw/RWVirtualPageHeap.z/RWVirtualPageHeap

Text File | 1998-10-30 | 7.7 KB | 199 lines

RRRRWWWWVVVViiiirrrrttttuuuuaaaallllPPPPaaaaggggeeeeHHHHeeeeaaaapppp((((3333CCCC++++++++))))                                RRRRWWWWVVVViiiirrrrttttuuuuaaaallllPPPPaaaaggggeeeeHHHHeeeeaaaapppp((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     RWVirtualPageHeap - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/vpage.h>



              ((((AAAAbbbbssssttttrrrraaaacccctttt bbbbaaaasssseeee ccccllllaaaassssssss))))




DDDDeeeessssccccrrrriiiippppttttiiiioooonnnn
     This is an abstract base class representing an abstract page heap of
     fixed sized pages.  The following describes the model by which
     specializing classes of this class are expected to work.  You allocate a
     page off the abstract heap by calling member function aaaallllllllooooccccaaaatttteeee(((()))) which
     will return a memory "handle," an object of type RRRRWWWWHHHHaaaannnnddddlllleeee.  This handle
     logically represents the page. In order to use the page it must first be
     "locked" by calling member function lllloooocccckkkk(((()))) with the handle as an
     argument.  It is the job of the specializing class of RRRRWWWWVVVViiiirrrrttttuuuuaaaallllPPPPaaaaggggeeeeHHHHeeeeaaaapppp
     to make whatever arrangements are necessary to swap in the page
     associated with the handle and bring it into physical memory.  The actual
     swapping medium could be disk, expanded or extended memory, or a machine
     someplace on a network.  Upon return, lllloooocccckkkk(((()))) returns a pointer to the
     page, now residing in memory.  Once a page is in memory, you are free to
     do anything you want with it although if you change the contents, you
     must call member function ddddiiiirrrrttttyyyy(((()))) before unlocking the page.  Locked
     pages use up memory.  In fact, some specializing classes may have only a
     fixed number of buffers in which to do their swapping.  If you are not
     using the page, you should call uuuunnnnlllloooocccckkkk(((()))).  After calling uuuunnnnlllloooocccckkkk(((()))) the
     original address returned by lllloooocccckkkk(((()))) is no longer valid -- to use the page
     again, it must be locked again with lllloooocccckkkk(((()))).  When you are completely done
     with the page then call ddddeeeeaaaallllllllooooccccaaaatttteeee(((()))) to return it to the abstract heap.
     In practice, managing this locking and unlocking and the inevitable type
     casts can be difficult.  It is usually easier to design a class that can
     work with an abstract heap to bring things in and out of memory
     automatically.  Indeed, this is what has been done with class
     RRRRWWWWTTTTVVVVaaaallllVVVViiiirrrrttttuuuuaaaallllAAAArrrrrrrraaaayyyy<<<<TTTT>>>>, which represents a virtual array of elements of
     type TTTT.  Elements are automatically swapped in as necessary as they are
     addressed.

PPPPeeeerrrrssssiiiisssstttteeeennnncccceeee
     None

EEEExxxxaaaammmmpppplllleeee
     This example illustrates adding NNNN nodes to a linked list.  In this linked
     list, a "pointer" to the next node is actually a handle.






                                                                        PPPPaaaaggggeeee 1111






RRRRWWWWVVVViiiirrrrttttuuuuaaaallllPPPPaaaaggggeeeeHHHHeeeeaaaapppp((((3333CCCC++++++++))))                                RRRRWWWWVVVViiiirrrrttttuuuuaaaallllPPPPaaaaggggeeeeHHHHeeeeaaaapppp((((3333CCCC++++++++))))



              #include <rw/vpage.h>



              struct Node {
            int  key;
            RWHandle  next;
          };
          RWHandle head = 0;
          void addNodes(RWVirtualPageHeap& heap, unsigned N) {
            for (unsigned i=0; i<N; i++){
              RWHandle h = heap.allocate();
              Node* newNode = (Node*)heap.lock(h);
              newNode->key  = i;
              newNode->next = head;
              head = h;
              heap.dirty(h);
              heap.unlock(h);
            }
          }


PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrr
              RWVirtualPageHeap(unsigned pgsize);


     Sets the size of a page.





PPPPuuuubbbblllliiiicccc DDDDeeeessssttttrrrruuuuccccttttoooorrrr
              virtual ~RWVirtualPageHeap();


     The destructor has been made virtual to give specializing classes a
     chance to deallocate any resources that they may have allocated.

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              unsigned
          ppppaaaaggggeeeeSSSSiiiizzzzeeee() const;


     Returns the page size for this abstract page heap.










                                                                        PPPPaaaaggggeeee 2222






RRRRWWWWVVVViiiirrrrttttuuuuaaaallllPPPPaaaaggggeeeeHHHHeeeeaaaapppp((((3333CCCC++++++++))))                                RRRRWWWWVVVViiiirrrrttttuuuuaaaallllPPPPaaaaggggeeeeHHHHeeeeaaaapppp((((3333CCCC++++++++))))



PPPPuuuubbbblllliiiicccc PPPPuuuurrrreeee VVVViiiirrrrttttuuuuaaaallll FFFFuuuunnnnccccttttiiiioooonnnnssss
              virtual RWHandle
          aaaallllllllooooccccaaaatttteeee() = 0


     Allocates a page off the abstract heap and returns a handle for it.  If
     the specializing class is unable to honor the request, then it should
     return a zero handle.

              virtual void
          ddddeeeeaaaallllllllooooccccaaaatttteeee(RWHandle h) = 0;


     Deallocate the page associated with handle hhhh.  It is not an error to
     deallocate a zero handle.

              virtual void
          ddddiiiirrrrttttyyyy(RWHandle h) = 0;


     Declare the page associated with handle hhhh to be "dirty."  That is, it has
     changed since it was last locked.  The page must be locked before calling
     this function.

              virtual void*
          lllloooocccckkkk(RWHandle h) = 0;


     Lock the page, swapping it into physical memory, and return an address
     for it.  A nnnniiiillll pointer will be returned if the specializing class is
     unable to honor the lock.  The returned pointer should be regarded as
     pointing to a buffer of the page size.

              virtual void
          uuuunnnnlllloooocccckkkk(RWHandle h) = 0;


     Unlock a page.  A page must be locked before calling this function.
     After calling this function the address returned by lllloooocccckkkk(((()))) is no longer
     valid.















                                                                        PPPPaaaaggggeeee 3333